Skip to main content
Version: DeepHub 2023 R2 - 2.4.2

WebSocket API

Overview

This section describes the general Websocket publish / subscribe concept for connecting Location Cores and client services, and to exchange messages and events over a Websocket connection.

General omlox™ Publish / Subscribe Concept

Applications can subscribe and unsubscribe themselves to named topics. Data published to a topic will be received by all subscribers of that topic. All data sent to and received from the WebSocket connection is wrapped into the payload property of the wrapper object detailed in the next section.

To subscribe to a topic, the application sends a json encoded message. The server generates a response, either acknowledging a successful subscription / unsubscription or returns an error message.

The server also generates a subscription_id for a successful subscription. This allows an application to subscribe itself to the same topic multiple times with differing parameters and control each subscription separately. Subscriptions are otherwise automatically terminated when the websocket connection is closed.

Topics

The following named topics are available:

location_updates

This topic is used to retrieve real-time location updates, as well as sending location updates to the hub. Location data received by the hub is processed and then forwarded to all subscribers of this topic.

When receiving data for this topic, the payload of the wrapper object contains omlox™ Location objects.

location_updates:geojson

This topic is similar to location_updates, but instead of an omlox™ Location object GeoJson feature collections are returned as payload.

When receiving data for this topic, the payload of the wrapper object contains GeoJson feature collections.

collision_events

This topic is used to retrieve real-time collision events. The hub checks trackable movements for collisions and sends collision events when trackables: start to collide, continue to collide and end a collision.

When receiving data for this topic, the payload of the wrapper object contains omlox™ CollisionEvent objects.

fence_events

This topic is used to inform subscribers about geofence entry and exit events. The hub implementation checks location providers and trackables for fence events and sends appropriate events to subscribers of this topic immediately for each fence entry and fence exit event.

When receiving data for this topic, the payload of the wrapper object contains omlox™ FenceEvent objects.

fence_events:geojson

This topic is similar to fence_events, but instead of an omlox™ FenceEvent object, GeoJson feature collections are returned as payload.

When receiving data for this topic, the payload of the wrapper object contains GeoJson feature collections.

trackable_motions

This topic informs subscribers about movements of an omlox™ Trackable. For example, when one of the assigned omlox™ Location Providers changes its position.

When receiving data for this topic, the payload of the wrapper object contains omlox™ TrackableMotion objects.

provider_changes, trackable_changes, fence_changes, zone_changes

These topics inform subscribers about changes of objects of the specified type.

They contain a field event_type further specifying whether the change event is of type create, update, or delete. For create and update events, the payload contains the new (updated) version of the object. For delete, the payload contains the id of the deleted object.

Furthermore, they contain a field timestamp that contains the timestamp the DeepHub associates with the event.

WebSocket Data Objects

Data between client and server are exchanged using a wrapper object with the following structure:

NameTypeDescription
eventstringAny of message, subscribe, subscribed, unsubscribe, unsubscribed
topicstringTopic name
subscription_idintThe concrete topic subscription which generated the data
payloadarrayAn array containing valid omlox™ data objects (or empty)
paramsobjectAn optional object containing key-value pairs of parameters. Parameters usually match their REST API counterparts

The field event is always required for all data exchanged between client and server. Other fields are required depending on the event type. Concrete event based data structures are detailed in the respective sections below.

Example data object containing an omlox™ location object as payload:

{
"event": "message",
"topic": "location_updates",
"subscription_id": 123,
"payload": [
{
"position": {
"type": "Point",
"coordinates": [5, 4]
},
"source": "fdb6df62-bce8-6c23-e342-80bd5c938774",
"provider_type": "uwb",
"provider_id": "77:4f:34:69:27:40",
"timestamp_generated": "2019-09-02T22:02:24.355Z",
"timestamp_sent": "2019-09-02T22:02:24.355Z"
}
]
}

In case of an error, the server sends a json object with event type error and the following data structure:

NameTypeDescription
eventstringWill be error for an error object
descriptionstringA human readable error message
codeintError code

Example error object:

{
"event": "error",
"description": "Invalid data. The location data contains an invalid Position.",
"code": 10005
}

The error code can be used by applications to discern the type of the error, e.g. for error handling and messaging on the application side.

Possible error codes:

  • 10000: Event type is unknown
  • 10001: Unknown topic name
  • 10002: Subscription failed
  • 10003: Unsubscribe failed
  • 10004: Not authorized
  • 10005: Invalid payload data
  • 10006: Not authenticated
  • 10007: Invalid license

Subscribing to a Topic

Subscribing to a topic opens a connection to the websocket endpoint at e.g. ws://localhost:8081/deephub/v1/ws/socket. After successfully connecting, the client sends a subscribe request message to the server.

The subscribe request has the following structure:

NameTypeDescription
eventstringsubscribe
topicstringName of the topic, e.g. location_updates or fence_events
paramsobjectAn optional object containing key-value pairs of parameters. Parameters usually match their REST API counterparts

An example subscribe request to the location_updates topic:

{
"event": "subscribe",
"topic": "location_updates",
"params": {
"crs": "EPSG:4326"
}
}

Example subscribe request to fence events:

{
"event": "subscribe",
"topic": "fence_events"
}

Successful Subscription Response

The server responds to the subscribe request either with a success response or an error response. Upon successful subscription, the server responds with a subscribed event, a copy of the subscribed topic as well as the subscription_id for the concrete subscription.

It's important to keep the provided subscription_id on the client side in case the client wants to maintain multiple subscriptions to the same topic with different parameters. A client may however simply close it's connection, and all it's subscriptions will be cleaned up on the server side.

The subscription response has the following structure:

NameTypeDescription
eventstringOn success subscribed
topicstringName of the topic
subscription_idintTopic subscription id

Example server response for a successful subscription request:

{
"event": "subscribed",
"topic": "location_updates",
"subscription_id": 123
}

Unsubscribing

To unsubscribe, a client must either close the connection, or send an unsubscribe request with a concrete subscription id to the server.

The unsubscribe request has the following structure:

NameTypeDescription
eventstringMust be unsubscribe
subscription_idintTopic subscription id to unsubscribe from

Example unsubscribe object:

{
"event": "unsubscribe",
"subscription_id": 123
}

Unsubscribe Response

With a successful unsubscription, the server responds with an unsubscribed event.

Unsubscribe event structure:

NameTypeDescription
eventstringMust be unsubscribed
topicstringName of the topic
subscription_idintTopic subscription id from which the application was successfully unsubscribed

Example unsubscribe server response:

{
"event": "unsubscribed",
"topic": "location_updates",
"subscription_id": 123
}

Filtering & Subscription Parametrization

The publish / subscribe API allows to filter and transform data feeds by setting parameters as key / value pairs to the params section of a subscription request. The following example shows a subscription request to trackable motions with location data projected to UTM 32 (EPSG:32632) and filtering for a certain trackable id:

{
"event": "subscribe",
"topic": "trackable_motions",
"params": {
"crs": "EPSG:32632",
"id": "0b680db2-b39b-45be-be77-40d7d2296cb4"
}
}

Note: There can be any number of active subscriptions made by the same client to a topic. For example, it's possible to make two distinct subscriptions to the location_updates topic, where each subscription may filter for a different location provider. However, subscribing to the same topic with the same parameters twice will result in a subscription error.

The following parameters are available for the respective WebSocket topics.

Parameters for location_updates Topic

paramDescription
provider_idFilter events matching the given provider ID
sourceFilter events based on the source of the location (caution: foreign_id and zone_id are not cross-matched)
provider_typeFilter by omlox provider type (e.g., uwb, wifi, rfid)
associatedFilter events which are currently associated to an infrastructure (e.g., relevant for wifi systems)
accuracyFilter events where the location's accuracy is better (less) than or equal to the value provided
floorFilter events where the location's floor matches the provided value
crsProject location data to the given crs. Any crs supported by omlox can be set (e.g., local, EPSG:32632)
zone_idThe zone_id used for calculating the local coordinates, if crs is set to local.

Parameters for trackable_motions Topic

paramDescription
idFilter events matching the given trackable ID
provider_idFilter events matching the provider ID
nameFilter events matching the trackable name
accuracyFilter events where the accuracy of the trackables motion's location is better (less) than or equal to the value provided
floorFilter events where the floor of the trackable motion's location matches the provided value
crsProject location data to the given crs. Any crs supported by omlox can be set (e.g., local, EPSG:32632)
zone_idThe zone_id used for calculating the local coordinates, if crs is set to local.

Parameters for fence_events Topic

paramDescription
fence_idFilter events matching the given fence ID
foreign_idFilter events matching the given foreign ID
provider_idFilter events matching the provider ID which caused the fence event
trackable_idFilter events matching the trackable ID which was involved in the fence event
event_typeFilter for fence entry (region_entry) or fence exit (region_exit) events
object_typeFilter events by object type (one of trackable or location_provider)

Parameters for collision_events Topic

paramDescription
collision_id_1Filter events where one item of the collision pair matches a given id (e.g., trackable ID involved in the collision)
collision_id_2Same as collision_id_1. Note: When both collision_id_1 and collision_id_2 are set, events will effectively be filtered for collisions between these two trackables
collision_typeFilter events by collision type. One of collision_start, colliding, collision_end
floorFilter events where the floor of both collisions matches the provided value

Parameters for provider_changes, trackable_changes, fence_changes, zone_changes Topics

paramDescription
idFilter the events based on the id of the associated object
event_typeFilter events based on the event type. Supported event types are: create, update, and delete

Sending Data via WebSocket

A client can send / publish data to the server directly over the websocket connection without a subscription. For example, a client can send raw location data to the location_updates topic; the server processes the data in the same way as the /providers/locations API and then publishes the processed location data to subscribers of the location_updates topic.

The message sent to the DeepHub must have the following structure:

NameTypeDescription
eventstringMust be message
topicstringMust be either location_updates or proximity_updates
payloadarrayAn array containing topic specific omlox entities

Examples

Example message for the location_updates topic:

{
"event": "message",
"topic": "location_updates",
"payload": [
{
"position": {
"type": "Point",
"coordinates": [5, 4]
},
"source": "fdb6df62-bce8-6c23-e342-80bd5c938774",
"provider_type": "uwb",
"provider_id": "77:4f:34:69:27:40"
}
]
}

Example message for the proximity_updates topic:

{
"event": "message",
"topic": "proximity_updates",
"payload": [
{
"source": "fdb6df62-bce8-6c23-e342-80bd5c938774",
"provider_type": "rfid",
"provider_id": "77:4f:34:69:27:40"
}
]
}

Authorization

When authorization is enabled, each message sent to the DeepHub must contain a JWT token in the params section. The access token must be given in the token field and an additional (topic dependent) field like fence_id may be provided and will be checked for ownership.

For a topic subscription, this results in the following example message:

{
"event": "subscribe",
"topic": "fence_events",
"params": {
"token": "eyJhbG...",
"fence_id": "..."
}
}

Messages from a subscription will only be received if the permissions and ownership of the involved resources are satisfied in accordance to the required ownership.

Sending a location update via websocket presents the same requirements. However, providing an additional field provider_id is NOT supported. This is an example of a location update:

{
"event": "message",
"topic": "location_updates",
"params": {"token": "eyJhbG..."},
"payload": [{...}]
}

Details on how to configure the DeepHub for authentication with Websocket can be found here.